home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48hor1 / voyager.doc < prev    next >
Text File  |  1995-03-31  |  15KB  |  459 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                V o y a g e r   R e f e r e n c e   M a n u a l 
  13.  
  14.                                Derek S. Nickel 
  15.   
  16.                                    V1.0-6 
  17.  
  18.                                30 January 1991 
  19.      ================================================================ 
  20.         Overview 
  21.     ================================================================ 
  22.  
  23.     Voyager is a tool to interactively disassemble the memory (RAM or 
  24.     ROM) in the HP 48SX.  In this context, the term disassemble is 
  25.     used to refer to disassembly of both machine code (aka 
  26.     unassemble) and threaded instructions (aka unthread). 
  27.  
  28.     Voyager consists of several images: 
  29.  
  30.     VOYAGER.EXE    Main program 
  31.     DMPTOMEM.EXE    Converts ROM dump to Voyager MEM file 
  32.     BINTOMEM.EXE    Converts binary file to Voyager MEM file 
  33.  
  34.     The calculator's address space in Voyager is divided into "ports" 
  35.     (similar to the ports in the calculator itself).  The ports are: 
  36.  
  37.     Port 0: 00000-7FFFF 
  38.     Port 1: 80000-BFFFF 
  39.     Port 2: C0000-FFFFF 
  40.  
  41.     A 'module' can be loaded into one of Voyager's ports with the 
  42.     LOAD command.  The HP48 module is automatically LOADed into port 
  43.     0 when you invoke Voyager. 
  44.  
  45.     Each module consists of these files: 
  46.  
  47.     module.MEM    Voyager MEM file (memory dump) 
  48.     module.CA    Address Comments 
  49.     module.CC    Code Comments 
  50.     module.CAX    Index for the CA file 
  51.     module.CCX    Index for the CC file 
  52.  
  53.     The MEM file is required; the other files will be created, if 
  54.     absent.  [NOTE! See MEM.DOC in HORN2 before using Voyager. -jkh-] 
  55.  
  56.     The MEM file is an ASCII listing of the nibbles in the module to 
  57.     unthread or unassemble.  It can is produced by downloading via 
  58.     the Memory Scanner or KERMIT transfer and then filtered with 
  59.     either the DMPTOMEM or BINTOMEM programs. 
  60.  
  61.         Two comment files are used by Voyager. Both have the same format. 
  62.         Each line consists of the 5 nibble address being described, 
  63.         followed by a space and a one-line comment describing the 
  64.     address. Lines beginning with a '-' are considered deleted. 
  65.  
  66.     The CA file is the address comment file.  It provides comments 
  67.         explaining the purpose of address references.  For example, the 
  68.         DUP routine is at 1FB87.  Unthreading is done with the UNTHREAD 
  69.     or UT commands.  Unthreading 1FB87 yields: 
  70.  
  71.     Voyager> UT 1FB87 
  72.     1FB87: ; *** DUP (XLIB 2 269) *** 
  73.     1FB87: 02D9D ! Program 
  74.     1FB8C: 18AA5 ; Save last RPL token and verify DEPTH >= 1 
  75.     1FB91: 03188 ; Internal DUP 
  76.     1FB96: 0312B ! End Marker 
  77.      Each comment following the threaded routine address is stored in 
  78.         the CA file.  Note that comments that start with an exclamation 
  79.     point are generated by Voyager; Voyager knows about object 
  80.     prologs and can format in-line objects (including Programs) 
  81.     without assistance.  Comments that start with a semicolon are 
  82.     from the CA file.  Address comments are created and deleted with 
  83.     the CA and CAD commands. 
  84.  
  85.     Another example: the RPL routine at 14039 is a very deep 
  86.     internal routine to the code for ERRN.  It pushes the Last Error 
  87.     Number as a System Binary (also called "short" or "address" by 
  88.     some people). 
  89.  
  90.     Voyager> UT 14039 
  91.     14039: ; *** Push Last Err# as System Binary *** 
  92.     14039: 1403E ! Machine Code at 1403E 
  93.     1403E: 34FF607    LCHEX  706FF          ; Save Last Err# 
  94.     14045: 8D3B411    GOVLNG 114B3          ; Push @C.A as new System 
  95.     Binary 
  96.  
  97.     114B3: ; *** Push @C.A as new System Binary *** 
  98.     114B3: DA         A=C    A             
  99.     114B5: 8FB9760    GOSBVL 0679B          ; Save D,B,D1,D0 (uses C) 
  100.     114BC: 130        D0=A                 
  101.     114BF: 142        A=DAT0 A             
  102.     114C2: 8DC7530    GOVLNG 0357C          ; Push A as new System Binary 
  103.  
  104.     The CC file is a code comment file.  It provides comments 
  105.     explaining what the code at a particular address is doing.  When 
  106.     the corresponding address is unassembled, the comment is 
  107.     appended to the output line.  Code comments are created and 
  108.     deleted with the CC and CCD commands. 
  109.  
  110.     Note that GOTOs are followed.  This can be disabled or enabled 
  111.     with the SET MODE NOFOLLOW and SET MODE FOLLOW commands. 
  112.  
  113.     Example: the RPL routine at 03188 executes the inner-most code 
  114.     for the DUP routine (i.e. after error checking and setup has 
  115.     been done). It is an assembler routine with an RPL entry point, 
  116.     and unthreading the entry point yields: 
  117.  
  118.     Voyager> UT 03188 
  119.     03188: ; *** Internal DUP *** 
  120.     03188: 0318D ! Machine Code at 0318D 
  121.     0318D: CF         D=D-1  A              ; room on stack? 
  122.     0318F: 41F        GOC    03181          ; if not, make some 
  123.     03192: 143        A=DAT1 A              ; get obj @ TOS 
  124.     03195: 1C4        D1=D1- 5              ; push object again 
  125.     03198: 141        DAT1=A A             
  126.     0319B: 142        A=DAT0 A              ; continue RPL 
  127.     0319E: 164        D0=D0+ 5             
  128.     031A1: 808C       PC=(A)               
  129.  
  130.     The CAX and CCX files are index files for the CA and CC files. 
  131.      ================================================================ 
  132.         Conventions 
  133.     ================================================================ 
  134.  
  135.     UPPERCASE    Uppercase characters indicate a command or 
  136.             keyword.  These can be entered as either upper 
  137.             or lower case.  Most commands can be 
  138.             abbreviated. 
  139.  
  140.     lowercase    Lowercase is used as a placeholder for 
  141.             information that you would enter. 
  142.  
  143.     [optional]    Square brackets indicate an optional parameter 
  144.             or keyword. 
  145.  
  146.     addr        A five digit hexadecimal address address, a 
  147.             "." or a "$". 
  148.  
  149.             A "." means the next address or 'continue'. 
  150.  
  151.             A "$" means the last specified address or 
  152.             'repeat'.  The last specified address can be 
  153.             either explicitly specified or implicitly 
  154.             specified. 
  155.  
  156.             If addr is optional and omitted, it defaults to 
  157.             the next address (continue). 
  158.  
  159.     addr:addr    Indicates an address range.  You may omit either 
  160.             the start or end addresses.  The start address 
  161.             will default to 00000.  The end address will 
  162.             default to FFFFF.  You may also use the "." and 
  163.             "$" as specified above. 
  164.  
  165.             If you specify a single address without the 
  166.             range specifier (the ":") then the range is 
  167.             that single address. 
  168.  
  169.             For example:    Means: 
  170.             :        00000 to FFFFF 
  171.             :14D20        00000 to 14A20 
  172.             1175:        01175 to FFFFF 
  173.             3E7:400        003E7 to 00400 
  174.             2B7        002B7 only 
  175.      ================================================================ 
  176.         Voyager Quick Reference 
  177.     ================================================================ 
  178.  
  179.     CA addr text 
  180.     CAD addr 
  181.     CC addr text 
  182.     CCD addr 
  183.     CL addr 
  184.     DUMP [addr] 
  185.     DA [addr] 
  186.     DH [addr] 
  187.     DT [addr] 
  188.     EXAMINE HASH_TABLE addr lib-no 
  189.     EXAMINE LINK_TABLE addr lib-no 
  190.     EXAMINE MESSAGE_TABLE addr lib-no 
  191.     EXIT 
  192.     FIND addr:addr partial-comment 
  193.     HELP 
  194.     LIST addr:addr 
  195.     LOAD port module 
  196.     MERGE port filename 
  197.     SEARCH addr:addr hex-string 
  198.     SET LIMIT number 
  199.     SET MODE FOLLOW 
  200.     SET MODE NOFOLLOW 
  201.     SET MODE INFO 
  202.     SET MODE NOINFO 
  203.     SET MODE PAGE 
  204.     SET MODE NOPAGE 
  205.     SET MODE PROMPT 
  206.     SET MODE NOPROMPT 
  207.     SHOW LIMIT 
  208.     SHOW MODES 
  209.     SHOW PORTS 
  210.     SHOW VERSION 
  211.     SORT port 
  212.     UNASSEMBLE [addr] 
  213.     UA [addr] 
  214.     UNCONTINUE [addr] 
  215.     U [addr] 
  216.     UNLOAD port 
  217.     UNTHREAD [addr] 
  218.     UT [addr] 
  219.      ================================================================ 
  220.         Voyager Command Dictionary 
  221.     ================================================================ 
  222.  
  223.     ---------------------------------------------------------------- 
  224.     CA addr text 
  225.  
  226.     Creates or replaces an Address Comment for the specified address. 
  227.  
  228.     ---------------------------------------------------------------- 
  229.     CAD addr 
  230.  
  231.     Deletes the Address Comment for the specified address. 
  232.  
  233.     ---------------------------------------------------------------- 
  234.     CC addr text 
  235.  
  236.     Creates or replaces a Code Comment for the specified address. 
  237.  
  238.     ---------------------------------------------------------------- 
  239.     CCD addr 
  240.  
  241.     Deletes the Code Comment for the specified address. 
  242.  
  243.     ---------------------------------------------------------------- 
  244.     CL addr 
  245.  
  246.     Lists the Address and Code comments for the specified address. 
  247.  
  248.     ---------------------------------------------------------------- 
  249.     DUMP [addr] 
  250.     DA [addr] 
  251.     DH [addr] 
  252.     DT [addr] 
  253.  
  254.     Displays the contents of memory at the specified address.  The 
  255.     number of lines displayed can be changed with the SET LIMIT 
  256.     command.  DUMP displays the information in the current dump 
  257.     mode (defaults to HEX).  DA, DH and DT set the dump mode to 
  258.     ALTERNATE, HEX or TEXT and then displsy the information. 
  259.  
  260.     ---------------------------------------------------------------- 
  261.     EXAMINE HASH_TABLE addr lib-no 
  262.  
  263.     Examines the Binary Integer at the specified address as if it 
  264.     were the Hash Table for the specified library. 
  265.  
  266.     ---------------------------------------------------------------- 
  267.     EXAMINE LINK_TABLE addr lib-no 
  268.  
  269.     Examines the Binary Integer at the specified address as if it 
  270.     were the Link Table for the specified library. 
  271.  
  272.     ---------------------------------------------------------------- 
  273.     EXAMINE MESSAGE_TABLE addr lib-no 
  274.  
  275.     Examines the Array of String at the specified address as if it 
  276.     were the Message Table for the specified library. 
  277.      ---------------------------------------------------------------- 
  278.     EXIT 
  279.  
  280.     Exit Voyager and return to DOS. 
  281.  
  282.     ---------------------------------------------------------------- 
  283.     FIND addr:addr partial-comment 
  284.  
  285.     Searches the Address Comment files for the specified partial 
  286.     comment.  The case of the comment is ignored. 
  287.  
  288.     For example:  To search for all occurrences of "prolog" in the 
  289.     range 2000 to 3000, you would say: 
  290.  
  291.     Voyager> FIND 2000:3000 prolog 
  292.  
  293.     ---------------------------------------------------------------- 
  294.     HELP 
  295.  
  296.     Provides brief help on Voyager commands. 
  297.  
  298.     ---------------------------------------------------------------- 
  299.     LIST addr:addr 
  300.  
  301.     List the Address Comments in the specified range. 
  302.  
  303.     For example: list the address comment for 3ADA. 
  304.  
  305.     Voyager> LIST 3ADA 
  306.  
  307.     For example: list all the address comments from 3B234 to 3DB15. 
  308.  
  309.     Voyager> LIST 3B234:3DB15 
  310.  
  311.     ---------------------------------------------------------------- 
  312.     LOAD port module 
  313.  
  314.     Loads the specified module into the specified port.  If a module 
  315.     has already been loaded in that port, the old module is unloaded 
  316.     first.  The comment files are created if they are missing.  The 
  317.     index files are automatically recreated if they are out-of-date 
  318.     or missing.  The required MEM file (module.MEM) can be created 
  319.     with either the BINTOMEM or DMPTOMEM programs. 
  320.  
  321.     For example: load the REV module into port 1. 
  322.  
  323.     Voyager> LOAD 1 REV 
  324.      ---------------------------------------------------------------- 
  325.     MERGE port filename 
  326.  
  327.     Merges the comments in the specified file into the address 
  328.     comment file for the specified port.  Only new comments are 
  329.     added to the comment file.  Existing comments are not 
  330.     overwritten. 
  331.  
  332.     The format of the comments in the file to be merged can be up to 
  333.     255 characters long and must be in this format: 
  334.  
  335.     <hex-address><separator><comment> 
  336.  
  337.     Where: 
  338.     <hex-address> = a 1 to 5 digit hexadecimal address. 
  339.     <separator> = a single character followed by optional whitespace. 
  340.     <comment> = any text, up to the new-line character. 
  341.  
  342.     ---------------------------------------------------------------- 
  343.     SEARCH addr:addr hex-string 
  344.  
  345.     Search part of the memory.  Hex-string specifiers the data for 
  346.     which to search.  For example, to search for references to the 
  347.     internal DUP command (at address 03188), you would say: 
  348.  
  349.     Voyager> SEARCH : 03188 
  350.  
  351.     To search for a hex-string in Memory Scanner format (backwards), 
  352.     you would prefix the hex-string with a single quote.  For 
  353.     example (this is equivalent to the previous example): 
  354.  
  355.     Voyager> SEARCH : '88130 
  356.  
  357.     ---------------------------------------------------------------- 
  358.     SET LIMIT number 
  359.  
  360.     Sets the number of lines displayed by the UNASSEMBLE and DUMP 
  361.     commands.  The default is ten. 
  362.  
  363.     ---------------------------------------------------------------- 
  364.     SET MODE FOLLOW 
  365.     SET MODE NOFOLLOW 
  366.  
  367.     Specifieds whether or not the UNASSEMBLE command follows 
  368.     absolute gotos (GOTO, GOLONG and GOVLNG).  Conditional gotos 
  369.     (GOC, GONC, RTNC or RTNNC) that have a Code Comment of "BET" 
  370.     (Branch Every Time) are also subject to the same logic.  The 
  371.     default is FOLLOW. 
  372.  
  373.     ---------------------------------------------------------------- 
  374.     SET MODE INFO 
  375.     SET MODE NOINFO 
  376.  
  377.     Specifies whether or not information (debug) messages are 
  378.     displayed.  The default is NOINFO. 
  379.      ---------------------------------------------------------------- 
  380.     SET MODE PAGE 
  381.     SET MODE NOPAGE 
  382.  
  383.     Specifies whether or not Voyager pauses after a screen full has 
  384.     been displayed.  The default is PAGE. 
  385.  
  386.     ---------------------------------------------------------------- 
  387.     SET MODE PROMPT 
  388.     SET MODE NOPROMPT 
  389.  
  390.     Specifies whether or not the Voyager prompt is displayed.  The 
  391.     default is PROMPT. 
  392.  
  393.     ---------------------------------------------------------------- 
  394.     SHOW LIMIT 
  395.  
  396.     Displays the number of lines that will be displayed by the 
  397.     UNASSEMBLE and DUMP commands. 
  398.  
  399.     ---------------------------------------------------------------- 
  400.     SHOW MODES 
  401.  
  402.     Displays the various mode settings. 
  403.  
  404.     ---------------------------------------------------------------- 
  405.     SHOW PORTS 
  406.  
  407.     Displays which ports have been loaded. 
  408.  
  409.     ---------------------------------------------------------------- 
  410.     SHOW VERSION 
  411.  
  412.     Displays the software version for Voyager. 
  413.  
  414.     ---------------------------------------------------------------- 
  415.     SORT port 
  416.  
  417.     Sorts the address and code comment files for the specified port. 
  418.     The files are sorted by address and the index files are 
  419.     recreated.  You must fist LOAD the port before sorting it. 
  420.     Sorting is not required, but it will eliminate deleted comments 
  421.     and make the comment files nice and pretty for printing. 
  422.  
  423.     ---------------------------------------------------------------- 
  424.     UNASSEMBLE [addr] 
  425.     UA [addr] 
  426.  
  427.     Disassembles the memory as machine code starting at the 
  428.     specified address.  The number of lines displayed is specified 
  429.     with the SET LIMIT command. 
  430.      ---------------------------------------------------------------- 
  431.     UNCONTINUE [addr] 
  432.     U [addr] 
  433.  
  434.     Continues disassembly based on the last mode (unassemble or 
  435.     unthread). 
  436.  
  437.     ---------------------------------------------------------------- 
  438.     UNLOAD port 
  439.  
  440.     Unloads the module in the specified port. 
  441.  
  442.     ---------------------------------------------------------------- 
  443.     UNTHREAD [addr] 
  444.     UT [addr] 
  445.  
  446.     Disasembles one object starting at the specified address. 
  447.      ================================================================ 
  448.     BINTOMEM input[.BIN] [output[.MEM]] 
  449.     (program) 
  450.  
  451.     Converts a binary file into a flat memory dump (Voyager format). 
  452.  
  453.     ================================================================ 
  454.     DMPTOMEM input[.DMP] [output[.MEM]] 
  455.     (program) 
  456.  
  457.     Converts a Memory Scanner dump into a flat memory dump (Voyager 
  458.     format). 
  459.